/******************************************************************************/
/**
*   @file   bat.h
*   @brief  API of the Binary AT (BAT) library which provides functions
*           for conveying of AT commands represented as C structures.
*
*   @par
*   Copyright 2002 Texas Instruments.
*   All rights reserved.
*
*   @par
*   This file is confidential and a trade secret of Texas Instruments.
*   The receipt of or possession of this file does not convey
*   any rights to reproduce or disclose its contents or to
*   manufacture, use, or sell anything it may describe, in
*   whole, or in part, without the specific written consent of
*   Texas Instruments.
*
*   @author Sven Kasner
**/
/******************************************************************************/


#ifndef BAT_H
#define BAT_H

/**
* @FB Telephony Interface (FB121)
* @INTERFACE_EXTERNAL
*/

#ifndef __TYPEDEFS_H__
#include "tapibat_typedefs.h"     /* TI type definitions */
#endif

//#include "p_21_00_11_03441_bat_sap.h" /* to include the structs representing the AT commands */
#include "tapibat_bat_types.h"                /* to include the types for internal maintainance */
#include "tapibat_bat_cfg.h"                  /* to include the configuration settings */


/*********************************************************************************
 *
 * defines
 *
 *********************************************************************************/

/**
 * @brief This definition is deprecated and remains for backward compatibility.
 *        Do not use it in new code.
 */
#define BAT_INSTANCE_HEADER_SIZE ((unsigned short)sizeof(void*))

/**
 * @def  BAT_INSTANCE_SIZE
 * This size is required for the maintenance of a BAT Lib instance.
 * The application must allocated memory of (BAT_INSTANCE_SIZE + n * BAT_CLIENT_SIZE)
 * and pass the pointer to this memory with bat_new().
 */
#define BAT_INSTANCE_SIZE ((unsigned short)sizeof(T_BAT_instance_maintain) + (unsigned short)L2P_MAINTAIN_SIZE)

/**
 * @def  BAT_CLIENT_SIZE
 * This size is required for the maintenance of a BAT client.
 * The application must allocated memory of (BAT_INSTANCE_SIZE + n * BAT_CLIENT_SIZE),
 * where n is the number of clients the application wants to open in a BAT Lib instance,
 * and pass the pointer to this memory with bat_new().
 */
#define BAT_CLIENT_SIZE ((unsigned short)sizeof(T_BAT_client_maintain))


/*********************************************************************************
 *
 * enumerations
 *
 *********************************************************************************/

/**
 * @enum T_BAT_return
 * @brief Return and error codes of API functions and callbacks
 */
typedef enum
{
  BAT_OK = 0,         /**< OK, no error occured */
  BAT_BUSY_RESOURCE,  /**< Currently busy */
  BAT_ERROR           /**< Error */
} T_BAT_return;

/**
 * @enum T_BAT_event
 * @brief Events for bat_ctrl() [APP ==> BAT]
 */
typedef enum
{
  BAT_ABORT = 0,         /**< Abort currently running AT command */
  BAT_APP_READY_RESOURCE /**< Ready again after busy (Application) */
} T_BAT_event;

/**
 * @enum T_BAT_signal
 * @brief Signals given in the callbacks [BAT ==> APP]
 */
typedef enum
{
  BAT_NEW_INSTANCE_SUCCEED = 0, /**< BAT Lib instance created */
  BAT_NEW_INSTANCE_FAIL,        /**< BAT Lib instance failed */
  BAT_OPEN_CLIENT_SUCCEED,      /**< Client of BAT Lib instance created */
  BAT_OPEN_CLIENT_FAIL,         /**< Client of BAT Lib instance failed */
  BAT_ABORT_COMMAND_SUCCEED,    /**< aborting of current AT command succeeded */
  BAT_ABORT_COMMAND_FAIL,       /**< aborting of current AT command failed */
  BAT_READY_RESOURCE            /**< Ready again after busy (BAT Lib instance)*/
} T_BAT_signal;


/*********************************************************************************
 *
 * structures
 *
 *********************************************************************************/

/**
 * @struct T_BAT_ctrl
 * @brief Consists of the events for bat_ctrl().
 * @see T_BAT_event
 */
typedef struct
{
  T_BAT_event  event; /**< see T_BAT_event */
} T_BAT_ctrl;


/*********************************************************************************
 *
 * function declarations
 *
 *********************************************************************************/

/**
 * @brief This function is deprecated and remains for backward compatibility.
 *        Do not use it in new code.
 */
extern T_BAT_return bat_init   (void            *mem,
                                unsigned char    num);

/**
 * @brief This function is deprecated and remains for backward compatibility.
 *        Do not use it in new code.
 */
extern T_BAT_return bat_deinit (void);

/**
 * @brief Create a new BAT Lib instance
 * @par
 * This function creates a new instance of the BAT library and also establishes
 * a communication channel to the modem. This is an asynchronous event and therefore
 * a callback function must be given to get informed.
 * The application which calls this function must provide the memory for internal maintenance
 * of the instance and the number of client channels associated to this instance.
 * (BAT_INSTANCE_SIZE + num * BAT_CLIENT_SIZE).
 * The configuration for the underlying transport mechanism can be configured in this way:
 * @code
 * config.adapter.gdd_if = gdd_func_dio;
 * config.adapter.cap.dio_cap.mtu_size = 300;
 * config.device = DEVICE_PACKET;
 * config.l2p.protocol_id = L2P_SP_PSI;
 * @endcode
 * @param [out] instance            The handle of the newly created BAT Lib instance.
 * @param [in]  mem                 The memory for the instance maintenance.
 * @param [in]  num                 The number of client channels the application wants to use with this instance.
 * @param [in]  config              The configuration of the underlying transport mechanism.
 * @param [in]  instance_signal_cb  The callback to get informed about (un)successfull instance creation and communication channel.
 * @return BAT_ERROR : Was not able to contact the underlying transport mechanism.
 * @return BAT_OK : Was able to contact the underlying transport mechanism.
 */
extern T_BAT_return bat_new    (T_BAT_instance  *instance,
                                void            *mem,
                                unsigned char    num,
                                T_BAT_config    *config,
                                void           (*instance_signal_cb)(T_BAT_signal signal));

/**
 * @brief Deletes a BAT Lib instance
 * @par
 * Deleting of a BAT Lib instance depends on the dynamic behaviour of the application.
 * If the lifetime of the application is static as long as the mobile is powered on,
 * then the BAT Lib instance can exist in the same way. No need to delete it.
 * @pre If there is the need to delete an instance, then all client channels must be closed before.
 * @see bat_close()
 * @param instance  The number as given in the out parameter of bat_new().
 * @return BAT_ERROR : When invalid instance handle has been given,
 *                     not all client channels have been closed before
 *                     or underlying transport mechanism could not been reached.
 * @return BAT_OK : Instance and communication channel to modem have been deleted/closed.
 */
extern T_BAT_return bat_delete (T_BAT_instance   instance);

/**
 * @brief Opens a client channel
 * @par
 * This function opens a client channel to the modem. This is an asynchonous event and therefore
 * a callback function must be given to get informed. It is possible to open several client channels
 * when the BAT Lib instance has been created with more than one client channel maintenance memory.
 * @pre A BAT Lib instance has been created.
 * @see bat_open()
 * @param [in]  instance     The instance handle provided by bat_new().
 * @param [out] client       The handle of the newly created client.
 * @param [in]  response_cb  The callback for intermediate and final result codes
 * @param [in]  signal_cb    The callback to get informed about (un)successfull opening of client channel.
 * @return BAT_ERROR : When invalid instance handle has been given or underlying transport mechanism could not been reached.
 * @return BAT_BUSY_RESOURCE : Underlying transport mechanism is currently busy.
 * @return BAT_OK : Was able to contact the underlying transport mechanism.
 */
extern T_BAT_return bat_open   (T_BAT_instance   instance,
                                T_BAT_client    *client,
                                int            (*response_cb)(T_BAT_client client,
                                                              T_BAT_cmd_response *response),
                                void           (*signal_cb)  (T_BAT_client client,
                                                              T_BAT_signal signal));

/**
 * @brief Register for unsolicited indications
 * @par
 * Unsoliticed indications are broadcasted by the modem to subscribed applications.
 * Subscription is done by providing a callback associated to a BAT Lib instance.
 * If the instance has several client channels, but only one of them should receive
 * the unsolicited indications, then the same callback function pointer of this client
 * can be used due to the fact that the signature of the callback is the same.
 * To distinguish whether the callback has been called with intermediate/final result code
 * or with unsolicited indications bat_uns_open() gives back a different client handle
 * than bat_open().
 * @see T_BAT_client
 * @pre A BAT Lib instance has been created.
 * @param [in]  instance     The instance handle provided by bat_new().
 * @param [out] client       The handle for unsolicited indications.
 * @param [in]  unsolicited_result_cb  The callback for unsolicited indications
 * @return BAT_ERROR : When invalid instance handle has been given.
 * @return BAT_OK : callback has been registered.
 */
extern T_BAT_return bat_uns_open(T_BAT_instance  instance,
                                 T_BAT_client   *client,
                                 int           (*unsolicited_result_cb)(T_BAT_client client,
                                                                        T_BAT_cmd_response *response));

/**
 * @brief Close a client channel
 * @par
 * This function closes a client channel to the modem.
 * This is an asynchronous event and the application is informed about (un)successful closing
 * of an client channel by the signal_cb given as callback with bat_open().
 * @param client The handle of this client.
 * @return BAT_ERROR : When invalid client handle has been given or underlying transport mechanism could not been reached.
 * @return BAT_BUSY_RESOURCE : Underlying transport mechanism is currently busy.
 * @return BAT_OK : Was able to contact the underlying transport mechanism.
 */
extern T_BAT_return bat_close  (T_BAT_client     client);

/**
 * @brief Sending of an binary AT command
 * @par
 * The sending of an binary AT command is a straight forward manner.
 * There is to fill the provided structure corresponding to an AT command as defined in 27.007, 27.005
 * or as defined in the AT_Command_Description_TI_Specific_8415_052.doc.
 * There is also an AT command discriminator as unique identifier, because all AT command structures
 * are organized as pointer in a union. The discriminator is needed at receiver side to recognize the actual AT command.
 * @note
 * All binary AT command/response/indication structures and their discriminators are generated by TI build chain.
 * The structure descriptions are done in a special interface editor which is currently not able to embed
 * this kind of documentation statements.
 * @par
 * Following is an example how to send a binary AT command
 * @code
 *    T_BAT_return res;
 *    T_BAT_cmd_send cmd;
 *    T_BAT_cmd_set_plus_cfun cfun;
 *
 *    memset(&cfun, FALSE, sizeof(cfun));
 *    cmd.ctrl_params = BAT_CMD_SET_PLUS_CFUN; <== the discriminator
 *    cmd.params.ptr_set_plus_cfun = &cfun;
 *
 *    cfun.fun = BAT_CFUN_FUN_FULL;
 *    cfun.rst = BAT_CFUN_RST_NO_RESET;
 *
 *    res = bat_send(client, &cmd);
 *    switch (res)
 *    {
 *      case BAT_OK:
 *        ...whatever the application needs to do here...
 *        break;
 *      case BAT_BUSY_RESOURCE:
 *        ...whatever the application needs to do here...
 *        break;
 *      case BAT_ERROR:
 *        ...whatever the application needs to do here...
 *        break;
 *      default:
 *        ...whatever the application needs to do here...
 *    }
 * @endcode
 * For the appliation there is no need to allocate memory for the AT command structure.
 * The BAT library takes care that the command structure is done persistent for conveying to the modem.
 * @param client The handle of this client.
 * @param cmd Structure of unique AT command identifier and a union of pointer to actual AT command structure.
 * @return BAT_ERROR : When invalid client handle has been given or underlying transport mechanism could not been reached.
 * @return BAT_BUSY_RESOURCE : Underlying transport mechanism is currently busy.
 * @return BAT_OK : Was able to contact the underlying transport mechanism.
 */
extern T_BAT_return bat_send   (T_BAT_client     client,
                                T_BAT_cmd_send  *cmd);

/**
 * @brief Control statement to BAT
 * @par
 * This function is used to abort a currently running command or to indicate to the BAT Lib
 * that the application is ready again after a busy condition.
 * @param client The handle of this client.
 * @param ctrl @see T_BAT_ctrl
 * @return BAT_ERROR : When invalid client handle has been given or underlying transport mechanism could not been reached.
 * @return BAT_BUSY_RESOURCE : Underlying transport mechanism is currently busy.
 * @return BAT_OK : Was able to contact the underlying transport mechanism.
 */
extern T_BAT_return bat_ctrl   (T_BAT_client     client,
                                T_BAT_ctrl      *ctrl);

#endif /*BAT_H*/


